import { Meta } from '../../.storybook/components';

<Meta title="Contributing/Code Conventions" />

# Code Conventions

When developing components in Circuit UI, we have a few development principles you should keep in mind. They will help you with picking good names, design clear & understandable APIs, and keep things consistent.

## Best Practices

**Every component must be thoroughly tested.** If the component is purely representative (e.g. simple, styled components), a snapshot test is sufficient. If the component is interactive, you should do your best to test the interaction on a unit level.

**Ensure accessibility and autocompletion.** Every component should have a minimum of an accessibility test asserted with `jest-axe`. You should manually check mouse, touch, and keyboard accessibility as well as good screen reader support. You should also make a special effort to properly enable autocompletion for relevant fields, using the proper input names and autocomplete properties.

**All translated text should be provided as props with English defaults.** It must be possible for all user-facing text inside a component to be replaced with translated versions. This also makes it easier to stick to content guidelines by providing a good starting example.

**Documentation is part of your component.** Be sure to write meaningful documentation about best practices / usage guidelines when creating or updating existing components. You can use existing documentation for reference.

## Component Design Principles

**Keep the API small.** As much as possible, avoid exposing too many options for configuring a component. The exception is if you are wrapping an existing third-party library, you may have a good reason to simply pass along all additional props to ensure API compatibility with that third-party library.

## Naming Principles

**Use obvious and transparent naming.** Our components should use names that are as standard as possible. Opt for a more verbose name rather than a creative or clever one. When in doubt, you can look at several other component libraries for inspiration.

**Opt for one- or two-word component and prop names.** When possible, stay
concise as long as you can remain clear as well.

**Handlers should be written as `onVerb`.** Or (if needed) `onVerbNoun` rather than `onNounVerb`. For example, if you cannot reasonably name your event handler `onSelect` because it is overly vague for your use-case, instead opt for something like `onSelectFruit` rather than `onFruitSelect`.

If at all possible, stick to standard names you'd find in the DOM or React APIs like `onClick`. This helps make our APIs more predictable!

```tsx
// Do: Use standard component names and short prop names
<DatePicker onClick={fn} nextButton="Next" prevButton="Previous" />

// Don't: Come up with unusual component names or name handlers without the `on` prefix
<CalendarTag selectDate={fn} />
```
